Sharing Your Brilliance with the World

Matt Pettis
2019-08-15

… because you are awesome

You see things...

  • … that others don't see…
  • … and others need to see…
  • … let's go to the code.

Your Genius Insights are Eclipesed by Technical Difficulties

  • Results and comments not together.
  • Images in another pane (if in RStudio) or saved to separate file.
  • You have to click around for other pictures.

Your Genius Insights are Eclipsed by Technical Difficulties

Enter R Markdown

… To the code!

Key R Markdown Pieces: Header

Key R Markdown Pieces: Header

Key R Markdown Pieces: Header

Key R Markdown Pieces: Header

Key R Markdown Pieces: Header

Key R Markdown Pieces: Header

Key R Markdown Pieces: Header

Other key features:

  • Numbering sections
  • Code folding
  • Custom CSS

See: https://bookdown.org/yihui/rmarkdown/html-document.html

Key R Markdown Pieces: Commentary

Key R Markdown Pieces: Code, Images

Key R Markdown Pieces: Code, Tables

Key R Markdown Use Cases

  • Automated reports: cron jobs, data integrity checks.
  • Avoid manual powerpoint presentations.
  • Taking notes while talking to yourself
  • Reproducible research

Opinion: How to use Markdown reports

  • Start report with executive summary and what to expect to see in report, highlights.
  • As much global setup work done at beginning.
  • Make analysis sections (see next).
  • Auto-generate Table of Contents.

Opinion: How to use Markdown reports

  • Break work into a chunk that answers a question.
  • Record what you expect to see.
  • Record what you actually saw.
  • Output code and artifacts that support the analysis.

Sidebar: RMarkdown vs Notebooks (Jupyter)

  • … do not use to start fights.
  • Sequential, linear execution desireable.
  • Notebooks have source code and output formatting mixed.
    • … does not work nicely with git.

Sidebar: RMarkdown vs Notebooks (Jupyter)

  • … I don't like magic.

Blogdown

  • You have lots of insights to share, but blast emailing people your insights is found “annoying” to the less enlighted.
  • Many “easy” website solutions are overkill on one hand, and don't support the tech analysis features nicely on the other hand.
  • See: https://bookdown.org/yihui/blogdown/

Blogdown: Setup

Blogdown: Live Demo?

  • Install blogdown
  • Create new blogdown site via New Project...
  • In 'Addins, serve site, and then create new blogpost.
  • Show in browswer.

Blogdown: Netlify deploy

Blogdown: What is it giving you?

  • Separate website theming from content production.
  • Your content is highly leveraged from your RMarkdown skills.
  • Once configured, you can make a working RMarkdown file, and then just publish it.
  • Optimized for a static website.
  • Not locked in to web publishing platform.

Blogdown: What is it giving you?

Bookdown

Bookdown

  • You have a thematic collection of things to say.
  • They break naturally into chapters.
  • Options for distributed editing.
  • Read online as html, or convert to pdf, ebook, Word Doc for offline reading.

Bookdown: Demo

Summary

  • RMarkdown for prettier commentary, better documentation.
  • Blogdown for making sets of posts with very similar machinery to RMarkdown, pushable to website.
  • Bookdown for a self-contained, well, book, with very similar machinery to RMarkdown.
  • All of these leverage markdown

Resources: RMarkdown

Me, Your Presenter

Matt Pettis

Sr. Data Scientist, Trane Inc.